fix(devx): guard the last two run-on-import gate scripts — KNOWN_IMPORT_UNSAFE 2 to 0 - #14593

Fixes #10667

Sitting 4, the final sitting of the KNOWN_IMPORT_UNSAFE burn-down. The ledger held exactly the two files the changesets-v3 epic #9465 had fenced; that epic has since completed, releasing them.

Ledger: 2 to 0. Sittings 1-4 across the whole card: 35 to 10 to 5 to 2 to 0.

File surface — four files, the fourth authorized

Three files are the card's own surface. The fourth, scripts/pm/dispatch-gates.mjs, carries a one-pin fix that emptying the ledger makes unavoidable. It was escalated rather than taken, and authorized by the PM decision on the card — comment 5511119817, which widens the surface "for exactly that one pin". See "The pin the empty ledger broke" below.

git diff --stat origin/main...HEAD:

 scripts/check-changeset-no-major.mjs | 24 +++++++++++++++++++++++-
 scripts/check-empty-changeset.mjs    | 23 ++++++++++++++++++++++-
 scripts/check-entry-guard.mjs        |  5 +----
 scripts/pm/dispatch-gates.mjs        | 28 +++++++++++++++++++++-------
 4 files changed, 67 insertions(+), 13 deletions(-)

Both gate scripts had one offending top-level statement each — a trailing --self-test / --list / main dispatch chain — so both took the inverted 4-line insert. Zero re-indentation: the only line touched in each chain is its head, which becomes } else if (...) {.

scripts/check-entry-guard.mjs is touched only to delete the two ledger lines; the set becomes new Set([]). Its SHRINK-ONLY doc comment is untouched by design — the sentence "a file this rule newly reaches is a failure with one remedy, never a line in here" is exactly what keeps an empty set empty, and the :800 self-test assertions over the roster hold on an empty set (verified: 54 cases green).

The inversion check (sitting 3's ts-parse.mjs lesson), applied

Before guarding anything, the question sitting 3 raised: does any top-level statement here have to run for an importer?

No — nothing in the repo imports either file. Every reference is a spawn or prose:

• spawns: .github/workflows/pr-automation.yml (:766-767, :942), cut-rc.yml (:482-483, :492-493), and package.json (check:empty-changeset, check:changeset-gate-self-tests) — all node scripts/..., a child process, unaffected by an import guard.
• prose only: check-adr-0087-registration.mjs, objectui-changeset-digest.mjs, check-required-contexts.mjs, objectui-range.mjs, pm/dispatch-gates.mjs, check-entry-guard.mjs.
• a repo-wide grep for an import/import() of either module returns nothing.

So the only statement moved behind isEntrypoint is CLI dispatch, and neither guard silences a census. This is the check that would have caught ts-parse.mjs; here it clears.

What the guards actually fixed — measured, both directions

Import probe: node -e "import('./scripts/NAME.mjs').then(m => console.log('SENTINEL exports:', Object.keys(m).join(',')))".

The first is the worst shape in this class, and the one sitting 2 flagged as most dangerous: a silent success is indistinguishable from a clean import to any caller reading the exit status alone.

Zero behaviour change when invoked directly

Re-proven on the final commit d11a00a29 as a same-tree ablation: capture guarded output, revert both scripts to origin/main (pre-guard — isEntrypoint count 0/0 confirmed on disk), capture again, restore with git checkout HEAD --, prove the restore (both blob hashes match HEAD, git diff HEAD empty, guard count back to 3/3), then cmp.

check:entry-guard after

✓ check:entry-guard: 199 scripts/ file(s) — every entry guard goes through invoked-as.mjs;
  150 export bindings, 150 of them inert on import (0 known-unsafe, ⛔ SHRINK-ONLY).

Before this PR that read 148 of them inert on import (2 known-unsafe). The two ledger lines were deleted only after the gate named them STALE — never in the same breath as the guard:

❌  check:entry-guard — 2 stale KNOWN_IMPORT_UNSAFE entry/entries:
  scripts/check-changeset-no-major.mjs  — no longer runs on import
  scripts/check-empty-changeset.mjs  — no longer runs on import

The pin the empty ledger broke

Emptying the ledger turned one case in scripts/pm/dispatch-gates.mjs red — the #10784 ablation, which strips check:entry-guard's declared subtree hint and asserts the brand-new-file verdict falls back:

✗ …and it is the subtree declaration doing it: strip it and check:entry-guard goes back to silent

Measured through the tool's own exported discoverFamilies / classifyEntry:

hints NOW:                      ["scripts/**"]
verdict NOW (full):             matched          <- the pin above this one still passes
hints after strip:              []
verdict after strip:            undetermined     <- the pin demanded exactly: silent

PRE-CHANGE hints after strip:   ["scripts/check-changeset-no-major.mjs",
                                 "scripts/check-empty-changeset.mjs"]
PRE-CHANGE verdict after strip: silent

The ablation was passing only because the ledger still contributed two path literals as hints. That ledger is SHRINK-ONLY and reaching zero is its goal, so the sitting that empties it leaves the stripped hint set bare, the residual becomes undetermined, and the case reds over a gate that had not changed at all. The pin was calibrated against a debt ledger designed to disappear. Unreachable in sittings 1-3 — only the sitting that empties the set can hit it.

The fix pins the claim, not the spelling. The ablation exists to prove the subtree declaration is the load-bearing half — i.e. that without it the file is not matched. Both silent and undetermined are not-matched, so both are accepted, spelled as the explicit pair ['silent', 'undetermined'].includes(residual) rather than !== 'matched' so a new verdict value cannot slip through as a pass. The vacuity guard undeclared.hints.length < entry.hints.length is untouched. The case label now says NOT MATCHED instead of silent, and the residual verdict is carried into the failure detail so a future red names what it actually got.

The pin still discriminates — shown, not asserted

Two one-off mutations on the final commit, each proven on disk before running, each restored with git checkout HEAD -- and the restore proven by blob hash plus an empty git diff HEAD:

So the widened pin still fails when the subtree declaration is not what is doing the work, and still fails on a matched residual. It was not loosened into a tautology.

Gates

Union re-derived at the final commit d11a00a29 (clean working tree) with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands — provenance names objectstack-ai/objectstack at d11a00a29. The fourth file grew the union from 18 to 20 families: node scripts/check-self-test-wired.mjs and pnpm check:declared-population-live are new, and neither was in the first derivation — re-deriving after the surface widened is what caught them. Exit codes captured by redirect before any pipe.

19 RAN-PASS (exit 0): check:agent-test-spelling · check:bash32-floor · check:changeset-gate-self-tests · check:cli-command-ids · check:cross-package-test-inputs · check:declared-population-live ("158 of 202 famil(ies) declare a path population, and every one of them reaches this tree's 7985 tracked file(s)") · check:entry-guard · check:parse-guard · check:pnpm-filter-targets · check:ratchet-remedy-authority · check:watch-hint-literal · check:pm-dispatch-gates ("✓ dispatch-gates self-test: 1240 cases pass", gate exit 0 — run detached through scripts/pm/os-verify-lock.sh, held 439s, waited 320s) · check-changeset-no-major.mjs · check-ci-filter-parity.mjs · check-cross-package-test-inputs.mjs · check-empty-changeset.mjs · check-self-test-wired.mjs · check-shard-attestation.mjs · pm/bare-root-worklist.mjs --self-test ("none stale, none missing, none contradicted").

1 NOT MEASURED: check-test-completeness.mjs, exit 3 — its own PREREQUISITE NOT MET branch (it grades a saved turbo test log and the family names it with no argument). Its text is explicit that this is not a red, and CI, which tees the log and passes the path, never reaches that branch.

Changeset: none — scripts/** only, no package publishes, so the PR carries skip-changeset.

Generated by Claude Code

Generated by Claude Code